A.C.E. 1

home *** CD-ROM | disk | FTP | other *** search

/ A.C.E. 1 / ACE CD 1.iso / files / games / 1-l / apple200.lha / Apple2000 / Apple2000.doc < prev next >

Wrap

Text File | 1994-04-09 | 27.5 KB | 577 lines

APPLE 2000 The premier Apple ][ emulator for the Amiga by Kevin Kralian Copyright © 1994, Patents Pending All Rights Reserved ------------------------------------------------------------------------------ This program is freely distributable, as long as this instruction file is kept with the program, and no modifications are made to my program or instructions. This program is also SHAREWARE (well, more accurately, Tech-Ware). Payment is not mandatory, however, donating to me useful, enabling technical material will result in me creating other emulations... See below for more info. Standard Disclaimer: This program is AS IS; use it at your own risk! I assume no responsibility if this program or its use should cause something disastrous to happen or kill you. I may be contacted at "Kevin_Kralian@sacbbx.com" This program uses "ReqTools.library", Copyright © by Nico François. ------------------------------------------------------------------------------ REQUIREMENTS: o Amiga computer with Kickstart 2.0 or newer (3.0+ still untested) o A 68020+ CPU. Emulation WILL NOT WORK on a 68000 system at this time. o About 900k free RAM (preferably most of it FAST RAM) o ReqTools.library by Nico François o Apple ][ ROM image & disk controller ROM image (called _APPLE.ROM and _DISK.ROM) Recommended: o A two-button joystick (to emulate the Apple's two-button joystick) o A 68030 at ~25MHz (for full speed 1 MHz emulation) DESCRIPTION: "Apple 2000" is the premier Apple ][ emulator for the Amiga computer. At its current level it accurately emulates a 64K Apple ][+, including: o 6502 CPU o ALL video modes (Text, LoRes, HiRes, Mixed modes, etc) o 16k RAM card (64k computer) o 5¼" disk drive (via disk images) o Two button joystick o Keyboard o Sound The emulation also runs in a completely system friendly manner, multitasking properly with other programs. The two main goals were speed and accuracy. This was accomplished by hand coding the emulator in 100% machine language, optimization via instruction cycle analysis, and painstaking attention to Apple hardware details. I feel confident that this is the fastest, most complete Apple ][ emulator available for the Amiga computer (commercial, public domain, or otherwise). Some of the highlights of my emulation: o Apple 2000 video emulation is the most accurate around: - There is no "dithering" of the 16 Lo-Res colors. - The text supports inverse and flashing characters. - Two consecutive color pixels are drawn as white (as the Apple does). - There are no missing, skipped, or fat vertical lines on Hi-Res gfx. o Apple 2000 disk drive emulation supports loading of "DDD" Apple disk archives from any Amiga device (no home made archive format or conversions required). o Apple 2000 disk drive emulation also saves disk images in compressed "DDD" format automatically. o Apple 2000 emulation is able to instantly load and run Apple executable files from any Amiga device (better than a real Apple; no 'disk booting' required!). REASONS/WHY AN APPLE II EMULATOR? Good question! This is my first attempt at a large scale 68000 assembly program and I had nothing else in particular to write. Of course, I could always have tried to write a game or demo, however the point of this project was to learn 680x0 and more about the Amiga Operating Aystem. I did not want to delve into the hardware specifics of the Amiga (yet), such as taking over the copper, blitter, etc. An Apple ][ emulator was the perfect task. Why the Apple ][? Sentimental reasons. It's the computer I grew up with and learned to program on. Since I have a fundamental understanding of the Apple and because there aren't any other useable Apple emulators out there (I've seen 5 or 6), the task called to me. I wanted to be able to play all of my favorite games that I grew up with. Yes, they certainly are not cutting edge as far as the graphics and sound goes, but they certainly are playable! And I can overlook the cosmetics for some good gameplay (i.e, just like people appreciate classic cars or oldies music). Plus I wanted all of my friends to be able to play all of those great forgotten games...the classics! The original CASTLE WOLFENSTEIN, CHOPLIFTER, KARATEKA and CARMEN SANDIEGO. How many other multitasking versions of JUNGLE HUNT or ROBOTRON 2084 can you play while downloading a program? By writing this one emulator, the entire Amiga community is suddenly presented with over 10,000 (now multitasking) Apple ][ programs we wouldn't have otherwise been able to use (or play). After letting the idea stew in my head for 6 months, and much apparent rambling to my friends (who so nicely encouraged me by saying, "What? YOU write an emulator? And in C? UGH!"), I began coding. One month later, I brought my first creation over to a friends house to see how it worked on his system. After starting it up, we sat there. 30 seconds later we were still sitting there, looking at a white screen. Eventually, we watched as each little white character s-l-o-w-l-y was replaced by a black space. Two minutes later, after getting bored of waiting for it to finish clearing the screen, we gave up and played 2-player LEMMINGS. I knew the only way I was going to be able to make this program 'practical' was to do it in assembly. I finally bought DevPac 3. After writing a program to bounce 65,535 colored pixels around a screen, I felt ready and experienced. I began converting my routines for my emulator into assembly code. Almost two years later (and after rewriting most of my emulation 10 times) my emulator has finally matured enough to go out into the cold and brutal world. Here it is, ready to be challenged by thousands of Apple programs I have never even heard of, and ready to do its damndest to run them all! RUNNING THE EMULATION Make sure "ReqTools.library" is in your libs: directory and place "Apple2000", "_APPLE.ROM", and "_DISK.ROM" all in the same directory. Then from the CLI/Shell, CD to its directory and type "Apple2000". Now, assuming a little common sense (press the "OK" button on the window!), you will see a black screen with "Apple 2000" in a title bar at the top, and the words "Apple ][" immediately below it. Congratulations, you are now using an Apple ][ computer. The Apple is trying to boot a disk. I will assume you have a little knowledge on using an Apple ][. Here are some of the pertinant keys: KEY Function ------------ ------------------------------------------------------ DEL Apple "Reset" key. ctrl-DEL Similar to "Ctrl-Open Apple-Reset" on ][e, ][c, ][gs. Forces reboot, even if reset vectors have been changed. RAmiga-Q Quit the emulator (after verification). RAmiga-L Load Apple disk image or executable into the emulator. RAmiga-S Save Apple disk image. L-ALT (Like Open-Apple on ][e) Represents Apple Paddle Button #0 R-ALT (Like Closed-Apple on ][e) Represents Apple Paddle Button #1 (Alt keys do not affect other keystrokes to emulator) ^ | Arrow keys patched to be like Apple ][e, ][c, ][gs. <--+--> (Note: Apple ][+ had no Up/Down arrows, and most | older programs won't handle them as expected.) v NumPad only: 8 Trim Apple joystick center position in respective 4 5 6 directions. 2 "5" will reset it to default (of 127,127). LOADING DISKS/FILES Once the Apple is running, you'll probably want to load an Apple disk or executable. Here's how: at ANY time during emulation, feel free to press Right-Amiga-L to bring up the Load File requester. From this requester you may load Apple 5¼" disk images or executable files. Simply navigate to wherever the files are kept and load the file/disk image you want. Apple 2000 recognizes several types of load files: o Filenames with a <xxx> suffix are Dalton Disk Disintegrator archives (DDD was a common disk compression util for the Apple, similar to DMS for the Amiga) and the emulator will automatically decompress them! o Filenames with a .DISK suffix are raw disk images with no compression. They are capable of storing images of non-DOS and copy-protected disks, but are about 220k in size. This format is primarily due to early testing of the emulator and will be phased out (as well as any references to it). o Filenames with a .PROG suffix are executable files; these are single files that were runnable from Apple DOS 3.3/ProDos and did not require any disk access thereafter. These files now do not even require booting any Apple disk and are simply loaded into the appropriate Apple memory areas and started instantly (quicker and easier than a real Apple!). After loading a disk image (compressed or not), the emulator will ask you if you want to 'boot' the disk. If you choose not to, you have effectively just 'put the disk in the drive' (useful when you need to insert 'Disk 2'). On the other hand, loading an executable Apple file does not give you any choices and immediately runs it. This has all been designed to keep the emulator as clean and simple as possible in terms of starting and running Apple programs for the non Apple-literate user. Keep in mind, loading a disk image is the same thing as inserting the disk into the Apple drive. It will STAY there until you replace it with another disk (or some program erases that disk). Even after you load and run several executable Apple programs, hitting Ctrl-DEL (rebooting the Apple) will boot up the last DISK IMAGE you loaded (if any). This can be confusing if you don't know whats going on (i.e, after finishing playing MS. PACMAN and reseting the Apple, why is MUSIC CONSTRUCTION SET loading? Because the disk is still in the drive from before). SAVING DISK IMAGES Pressing Right-Amiga-S will bring up a requester to save a disk image. Disk images are automatically compressed when saved. Navigate your way through the directories (as you normally would), and enter a filename (like normal). The only rule here is that the filename MUST end with a > character (greater than sign). This is because the original DDD archives did not have any special identifying header, but merely relied on that trailing character (actually, DDD uses <###> where the #'s represent the number of sectors the file takes, but my emulation ignores that value and just checks for that last character). NOTE: Ultimately, these archives will be saved with an Apple ProDOS header so that files can be transferred right back to real Apples and decompressed. However, due to a lack of resources, I have not yet been able to implement this 'identical header' and currently disk-images will not transfer back to an Apple. This will be incorporated later. TRANSFERRING APPLE FILES To get an executable binary file from a real Apple to the Amiga is quite simple. Copy the file to a ProDOS disk (using a utility such as Copy ][+) and then transfer it via null-modem (or however you want) to the Amiga. Make sure to append a .PROG to the end of the file name so that it's recognized by the emulator. NOTE: At the moment, I require the conversion to ProDOS simply because ProDOS puts a standard header in front of the file that my emulator needs. I'll eventually allow files to be transferred directly from DOS 3.3. TRANSFERRING APPLE DISKS Only UNPROTECTED standard 16 sector Apple disks are currently useable. This eliminates copy protected software. Simply run Dalton Disk Disintegrator (do not use version 2.0! It has a bug! Use version 2.1) and use it to compress the disk into a file. Then, convert it to ProDOS and transfer it to an Amiga (as described in "Transferring Apple Files" above). Once on the Amiga, change the name to end in <xxx> because ProDOS strips out the <> characters. NOTE: Like with files, eventually this will not require the intermediate ProDOS conversion either. TRANSFERRING APPLE ROMS The Apple emulator, being true to form, requires the actual Apple ROM data in order for the Apple to do anything. The standard Apple ROMs in use were the 'AppleSoft ROMs that contained AppleSoft BASIC, the assembly language monitor, and autobooting code. So I suggest that you obtain the same ROM if you would like the same compatibility. The ROM image can be obtained by booting an Apple ][ or ][+ with DOS 3.3, then typing: BSAVE BASICROM,A$D000,L$2FFF to save it to disk. Also, the disk controller Rom is saved by typing: BSAVE DISKROM,A$C600,L$00FF Incidentally, the main ROM image is on Apple's "DOS 3.3 System Master" disk, called FPBASIC (which may be used instead). After saving these images to disk, use your favorite terminal software and a null modem cable (or real modems or whatever you like) to transfer these files to the Amiga. Once transferred to the Amiga, give these files the proper names and place them in the same directory as the Apple2000 executable. Theoretically, you can use the ROMs obtained from an Apple ][ clone (i.e, Franklin Ace, PineApple, etc.), but keep in mind that these ROMs were not 100% compatible (but were quite close). This would effectively make my emulation a "Franklin Ace Emulator". :-) However, you CANNOT use the ROM images from an Apple ][e, ][c, or ][gs (maybe eventually...we'll see)! Once on the Amiga, the filenames MUST be _APPLE.ROM and _DISK.ROM PADDLE/JOYSTICK EMULATION The Apple ][ commonly uses either 2 paddles, a joystick, or a graphics tablet (like a free-floating joystick). My emulation covers all bases. The paddles and graphics tablet emulation are handled with the mouse and the joystick emulation is handled with the joystick. The F9 key toggles between the two and displays your choice at the top of the screen. For the Joystick: The Apple ][ uses (unfortunately) the variable 'all-over-the-place' PC-type of joystick (with two buttons). This evolved from the earlier Apple days when paddles where common (PADDLE - a turning knob with a button, useful for playing PONG). Anybody having used these joysticks know the frustration of having to constantly 'center' or 'trim' the joystick for different programs. The emulation takes this into account also. The Amiga 'Atari-style' joystick in the normal joystick port is used (preferably, a true 2-button joystick). The center position defaults to the optimal center positions on an Apple (127 X 127). However, different games expect different centering values, which can be trimmed with the 2, 4, 6, & 8 keys on the numeric keypad (ONLY, see "Running Emulation"). For example, if you start CHOPLIFTER and your character drifts towards the left, press the "6" key to center the joystick more towards the right until your character no longer drifts! If you do not have a two button joystick, you have two choices. Go buy one, or else just use the Right-ALT key in lieu of the second button (by the way, the two ALT keys work great for pinball games like RASTER BLASTER). For the Paddles/Graphics Tablet: Some of the older Apple games were designed to be used with paddles, not joysticks. This is noticable in games (APPLE GALAXIAN) as in when you release the joystick, your ship automatically moves back towards the center point on the screen. This is exactly what would happen on a real Apple with a joystick. You need to use the paddle emulation here. Push F9, the top of the screen should say "Mouse", and now the mouse controls this stuff. The horizontal movement controls Paddle #0, and vertical movement controls Paddle #1. If you have a game that needs independant control of each paddle, you are out of luck (I'll get to that later). Programs designed for graphics tablets (KOALA PAD) or un-centered joysticks work great in this mode also, i.e, FANTAVISION, MISSILE COMMAND games, and most other free floating cursor control programs work ideally. The mouse works just like you would expect here. TECH NOTES Though the emulation is 100% system friendly and running in a standard intuition screen, it has to do a few tricks with copperlists in order to achieve the Apple mixed screen graphics. The side effect of this technique is that when you pull down screens in the foreground to reveal the Apple emulator in the background, there will be times that the display looks garbled and/or is flashing. This is normal...nothing is wrong. If you don't like it, then don't pull screens down in front of the emulation! (A man tells a doctor, "It hurts when I do this...", and the doctor tells him "Then don't do this.") My emulation uses innovative 6502 emulation routines, which are significantly faster than any other 6502 emulations that are available on the Amiga (commercial or otherwise). My Apple emulation also has the most accurate graphics emulation I have witnessed. As complex as this is, speed is always maintained by extensive use of complex lookup tables (several hundred K worth). The ONLY graphics glitch is that the Hi-Res graphics screens do not fill in the entire display width. That is, they leave a half-inch black border on each side of the display. Why? Because the Apple Hi-Res screen has a horizontal resolution of 280 pixels, and the Amiga's display has a minimum resolution of 320. Trying to stretch this display by leaving an empty pixel after every 7 pixels or drawing every 7th pixel twice, results in a highly distorted and uneven image. The Text modes and LoRes modes still use the entire screen width (to maintain aspect ratio). This slightly narrow display is only noticeable in the 'mixed Graphics/Text' mode, where text will be a little wider than the graphics above it. Also regarding Text and Graphics (but not a glitch, it's an improvement) is the fact that mixed Graphics and Text on the old Apple ]['s used to cause the text to be fringed with green and purple instead of being solid white. This fringing has absolutely no purpose, but is a mere artifact of the Apple video circuity. My emulation cleans it up with crisp & clean text output all the time (does anybody have any complaints?). Apple finally cleaned this up with the Apple ][gs and its RGB output (but introduced a couple other graphic glitches), so I believe my clean Text display is desirable. Some Apple programs use "unimplemented" 6502 instructions. These are instructions that are not official, but partially decode into doing a particular function (as discovered by many unorthodox programmers). My emulation does not support ANY unimplemented instructions, and will simply break upon hitting any of those instructions (with Apple ][ software, I have seen very few programs that do this). PLANNED IMPROVEMENTS Currently, emulation speed is pretty much as fast as possible under the current 'interpreted' method. A speedup of about 3X is possible if I do 'pre-interpretation' which essentially converts 6502 code to native 680x0 code ahead of time, then running it at full speed. However, this comes at a cost of excessive memory usage (I estimate using about 2 megs for the 64k Apple emulation). This could be considered if enough people are interested (this would be the final speed boost required for the A1200 owners if they have enough memory!), but is of low priority for now. A 68000 version is easily possible, but emulation is so slow at that point (games are frustratingly unplayable), that I haven't bothered to do one. I plan to add Apple printer & serial emulation (and redirection). This way you could redirect Apple printer output to an Amiga file or to an Epson emulator (to print Epson output to any Amiga Prefs printer). Or emulate the Apple serial card with an Amiga Modem, etc. I plan to (eventually) upgrade the entire emulation to Apple ][e / ][c status. This includes Apple "Double-Hi-Res" graphics, 128k RAM, and 80-column text. I have thought about writing a ProDOS driver allowing the Apple to access Amiga devices as an Apple hard drive (is anybody using the emulator this seriously?). I might tackle using a real 5¼" disk drive if enough people want it. WHAT ABOUT EMPLANT? My emulator, "Apple 2000" was (p)reviewed in Amiga Computing (Issue 71, March 94), inside a larger review for the Emplant card (there's even a screenshot where you can read my title bar, Apple 2000!). For all intents and purposes, the review makes it appear as if this program was written by, owned by, and coming soon from Utilities Unlimited, makers of the Emplant card (regardless, the reviewer loved it, noting that this was the fastest 6502 emulation he has seen). At several World Of Commodore shows, Jim Drew showed my early versions of "Apple 2000" to crowds of people during his presentations of his Emplant card. A friend even has a video-tape of Jim loading up and showing my emulator to a crowd when I asked, "What other emulators are you doing?" (before he knew who I was) at WOC in Pasadena, 1993. To set the record straight, I did send Utilities Unlimited several early exclusive 'evaluation' versions of my emulator to see if they were interested in purchasing it (for their Emplant package). But this program (Apple 2000) is not a part of the Emplant package! Utilities Unlimited was in no way involved with the development of this program. There was never an agreement made over ownership rights. Several proposals were submitted by me as per Jim Drew's requests for exclusive rights, but an agreement was never reached. The positive side effect of this is that you may use the Apple 2000 program without having to spend >$300! ABOUT THE AUTHOR "Apple 2000" was written by Kevin Kralian over the course of two years. He has spent time in the US Marine Corps 'finding himself'. He is now a full time college student, preparing to transfer to CSU, Sacramento. He has over 10 years of programming experience, including ADA, BASIC, C, Pascal, 6502 and 680x0 assembly. Programming interests focus on performance programming, including games and emulation. Career goals include firefighter (!?) and computer programmer. He may be contacted at "Kevin_Kralian@sacbbx.com" "PAYMENT" FOR THIS PROGRAM Though this program is being distributed freely as shareware, I do not expect monetary payment. My original intentions were simply to have my program be 'used' by the Amiga community, and I still feel the same way. I've worked long and hard on this program and the most rewarding thing to me know would be to simply know people are enjoying it! However, what I WOULD appreciate would be any technical references for any computer/hardware/platform. Let me explain... Many improvements in the Apple emulator are dependant upon me finding Apple technical reference material (i.e, unimplemented instructions, serial/parallel support, ProDOS harddrive support, etc). If you would like to see these features implemented, the biggest thing you can do is send me any tech material that could be helpful (i.e, "Whats Where In The Apple ][: An Atlas", "Beneath Apple DOS", "Beneath Apple ProDOS", etc). Also, some ideas for my next emulator include: Atari VCS (2600), GameBoy, Nintendo, Atari 400/800 and Commodore 64/128. Even though there are a few C-64 emulators out there, many people have urged me to do one "the right way" (ground has been broken and the C-64 emulation is underway already). I tend to want to do the old Atari VCS or Gameboy emulation. HOWEVER, in order to do this, I need the tech information that I cannot publically obtain. Do YOU want these game machines to be emulated (I do)? If you are one of those priviledged people who might have been involved in developing software for any of these machines or somehow have any tech info on these machines, please send me any and all tech information. *** I WILL *** make an emulator of these machines when I have enough tech information to do so. But I need your help. I am open to any suggestions, comments, or feedback. Let me know how the emulator works for you. Please let me know of anything that does not work (that works on a real Apple ][), and I will do my best to correct the problem. I am also interested in obtaining any Apple ][ programs people may have to test under my emulation. Anybody interested please contact me at "Kevin_Kralian@sacbbx.com" Particular things I'm looking for: o Whats Where in the Apple ][: An Atlas to the Apple computer o Beneath Apple DOS o Beneath Apple ProDOS o Apple Super Serial Card / Parallel card manuals o AmigaDOS Programmers Reference o Any 2.0+ Amiga ROM Kernal Manuals (I'm using 1.3) o ANY kind of tech info on Gameboy, Nintendo, or the old Atari VCS (there once was an Apple ][ card to program the Atari. Anybody have it?) o Any and all Apple ][ programs. o Any old Apple ][ hardware (I use a ][gs; its too different from ][+) o Any responses, reactions, suggestions, etc. on my emulation. o etc... CREDITS I owe lots of thanks to lots of people. Thank you my dearest JoAnnaBear for being so supportive of me and this project over the last two years, and for not going crazy over my many hours of "techno-babble", but just patiently smiling back as if you understood me. :-) Thank you Robbie for all your inspiration and encouragement. And thanks for your ice-cream sandwiches, twisted sense of humor, brainstorm sessions, and hundreds of hours worth of second-hand smoke (cough cough). Thank you for the book "Amiga Machine Language Programming Guide" - the very first 680x0 assembly book I've seen (blech!). By the way, this book was due back at the library in 1989. How are your games "To Sir With Love" and "The Piano" coming along? Oh yeah...and thanks for cleaning up and converting my docs to AmigaGuide format for me :-) Thank you Bill, for taking your family and moving far away (just kidding!). Thanks to those incredible guys at Computer Cafe. I appreciate how you let me use your various machines for debugging and testing during the development of my emulation. Without your help, I would have never been able to work out the '040 bugs, nor have seen my emulation running on a 28" monitor with cool 24 bit backgrounds. Thanks to Carmen Rizzolo, the computer artist extraordinaire! Your original artwork for my previous programs are utterly amazing. Without people like Carmen, where would we get cool 3D Star Trek and telephone objects? Thanks to Will, the only intelligent Mac owner I know. It was great to share ideas on high performance 6502 emulation with the 680x0. Have you finished your Mac version of your Apple ][ emulator yet? Thanks for that 'half' of the "Inside the Apple //e" manual. Did you ever find pages 1-110? Thank you Nico François, for your contribution to the Amiga community. ReqTools is a very polished piece of work, and I know that your work has saved me (and many others) hours of work trying to "recreate the wheel". (Reqtools.library is Copyright © by Nico François). Thanks to the many helpful people on the Internet, for helping me through many obscure programming and debugging challenges. Thanks to Apple Computer and Steve Wozniak for creating the original Apple ][ computer. And congratulations to Apple Computer for knowing how to market their computers and becoming a large, successful company. Maybe Commodore can learn a few things from you before they drive themselves out of business? Thanks to 'Dalton', for his "Dalton's Disk Disintegrator" (DDD) program on the Apple ][. My (de)compression routines were based on his routines and attempt to compress data in an identical, compatible way. And finally, thanks to the many people I do not have space to mention, and to all of the Amiga users who have made the Amiga scene as wonderful as it is.